from abc import ABC, abstractmethod
from typing import List, Any

from llama_index.core.schema import BaseNode
from llama_index.core.vector_stores.types import VectorStoreQuery, VectorStoreQueryResult


class VectorStoreInterface(ABC):
    """
    一个标准接口，用于与向量数据库进行交互，提供高级的增、删、查以及生命周期管理能力。
    """

    @abstractmethod
    async def add(self, nodes: List[BaseNode]) -> List[str]:
        """
        向集合中添加一批节点（包含文本、元数据和可选的向量）。

        Args:
            nodes: LlamaIndex 的 BaseNode 对象列表。

        Returns:
            被添加的节点的 ID 列表。
        """
        pass

    @abstractmethod
    async def delete(self, doc_ids: List[str]) -> None:
        """
        从集合中删除文档。

        Args:
            doc_ids: 需要删除的文档/节点的 ID 列表。
        """
        pass

    @abstractmethod
    async def query(
        self,
        query: VectorStoreQuery,
        **kwargs: Any,
    ) -> VectorStoreQueryResult:
        """
        使用一个高级查询对象执行向量搜索。

        Args:
            query: LlamaIndex 的 VectorStoreQuery 对象，封装了查询向量、top_k、过滤器等所有高级选项。

        Returns:
            一个 VectorStoreQueryResult 对象，包含查询到的节点、相似度等信息。
        """
        pass

    @abstractmethod
    async def aget_nodes(self, node_ids: List[str]) -> List[BaseNode]:
        """
        根据节点ID列表，异步地从存储中批量获取节点对象。

        Args:
            node_ids: 需要获取的节点ID列表。

        Returns:
            一个包含获取到的 BaseNode 对象的列表。
        """
        pass

    @abstractmethod
    async def delete_collection(self) -> None:
        """
        删除整个集合（例如，数据库中的一张表）。
        """
        pass

    @abstractmethod
    async def collection_exists(self) -> bool:
        """
        检查当前集合是否存在。

        Returns:
            如果集合存在，则返回 True，否则返回 False。
        """
        pass 